<?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
	
	<head>
		<meta http-equiv="Content-Language" content="en-gb" />
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <meta name="description" content="Clipping" />
		<title>PDF Graphics .NET documentation - Clipping</title>
		<link rel="stylesheet" href="../style/Help.css" type="text/css" />
	
	</head>
	
	<body>
		<div class="navigator">
			<span>
				<strong>PDF Graphics .NET</strong> :: <a href="..\Index.html">Help</a> :: <a href="..\Painting_graphics.html">Painting graphics</a> :: Clipping
			</span>
		</div>
		
		<h1>Clipping</h1>
							
		<p>
			Clipping operations restrict graphics operations to a specific part of the page. It is used to prevent graphics from
			spilling outside of pre-set bounds, or for special effects such as custom patterns.
			<ul>
				<li><a href="#ClippingGraphics">Clipping graphics</a></li>
				<li><a href="#ClipMasks">Clip masks</a></li>
				<li><a href="#SpecialEffects">Special effects</a></li>
			</ul>			
		</p>
			
		<h2><a name="ClippingGraphics"></a>Clipping graphics</h2>

		<p>
			To clip graphics, use the <span class="code">SetClip</span> method. All graphics from that moment on will be truncated to fit
			the specified clipping bounds.
		</p>
				
		<div class="sampleCode">g.FillRectangle(Rgb.GreenBrush, new Rectangle(0,0,70, 70));
g.SetClip(new Rectangle(10, 10, 50, 50));
g.FillEllipse(Rgb.RedBrush, new Rectangle(30, 30, 50, 50));</div>

		<p>
			In the example above, an ellipse is filled. It does not entirely fit inside the clipping bounds, so it is truncated.
			The rectangle behind the ellipse is not affected by the painting of the ellipse, except for the part within the clipping bounds.
		</p>
		
		<img src="../images/Clipping.jpg" />
		
    <h3>Multiple masks</h3>
    
    <p>
    	Calling <span class="code">SetClip()</span> a number of times results in a clip mask that is the intersection of the individual masks.
    	That means multiple clip masks <em>limit</em> the clip area. To create a clip mask with multiple shapes, use a
    	<span class="code">GraphicsPath</span> instance (see the section on <a href="#ClipMasks">Clip masks</a> below). The PDF standard does not allow an existing clip mask to be extended.
    </p>
    		
		<h3>Removing a clip mask</h3>
		
		<p>
			To remove the clipping mask at a later stage, the graphics state needs to be stored before the mask is applied, and then restored
			when the mask is no longer required. Below is a modification of the previous code:
		</p>

		<div class="sampleCode">g.FillRectangle(Rgb.GreenBrush, new Rectangle(0, 0, 70, 70));

g.BeginContainer();
g.SetClip(new Rectangle(10, 10, 50, 50));
g.FillEllipse(Rgb.RedBrush, new Rectangle(30, 30, 50, 50));
g.EndContainer();

g.DrawEllipse(Rgb.BluePen, new Rectangle(30, 30, 50, 50));</div>

		<p>
			This time, the graphics state is preserved before the clip mask is applied. The ellipse is painted as before, and truncated.
			Then, the original graphics state is restored and the ellipse is outlined in blue. Because the clip mask no longer applies,
			the entire ellipse is outlined.
		</p>
					
		<p><strong>Note:</strong>&nbsp;The clip mask is automatically removed when a new page is opened.</p>
					
		<h2><a name="ClipMasks"></a>Clip masks</h2>

		<p>
			In the examples above, the clip masks were based on rectangles. A clip mask can consist of a number of shapes, however.
			To create more detailed clip masks, specify an instance of <span class="code">GraphicsPath</span> when constructing eac
			mask. In the following example, a clip mask is created and a large circle is truncated by the mask.
		</p>
		
		<div class="sampleCode">GraphicsPath path = new GraphicsPath();
path.AddLine(0, 0, 50, 0);
path.AddLine(50, 0, 50, 50);
path.AddLine(50, 50, 25, 75);
path.AddLine(25, 75, 0, 50);
path.AddLine(0, 50, 0, 0);
path.Close();

g.SetClip(path);

g.FillEllipse(Rgb.RedBrush, new Rectangle(0,0, 100, 100));</div>
    
		<img src="../images/Clipping_Multiple.jpg" />
        
    <p>
    	Clips masks can be created with rectangles, paths (as in the example above), or text.
    </p>
    	
    	
		<h2><a name="SpecialEffects"></a>Special effects</h2>

		<p>
			A common use for clip masks is special effects. See the two examples below:
		</p>
			
		<h3>Example #1 - Star</h3>
		
<div class="sampleCode">GraphicsPath star = new GraphicsPath();
star.AddLine(10, 20, 10, 30);
star.AddLine(10, 30, 15, 25);
star.AddLine(15, 25, 20, 30);
star.AddLine(20, 30, 20, 20);

star.AddLine(20, 20, 30, 20);
star.AddLine(30, 20, 25, 15);
star.AddLine(25, 15, 30, 10);
star.AddLine(30, 10, 20, 10);

star.AddLine(20, 10, 20, 0);
star.AddLine(20, 0, 15, 5);
star.AddLine(15, 5, 10, 0);
star.AddLine(10, 0, 10, 10);

star.AddLine(10, 10, 0, 10);
star.AddLine(0, 10, 5, 15);
star.AddLine(5, 15, 0, 20);
star.AddLine(0, 20, 10, 20);
star.Close();

g.SetClip(star, 50, 50);

Brush starBrush = new RadialGradientBrush(
    Rgb.White, Rgb.Yellow, new Rectangle(50, 50, 30, 30));

g.FillRectangle(starBrush, new Rectangle(50, 50, 30, 30));</div>
		
		<img src="../images/Clipping_Special.jpg" />

		<p>
			A new graphics path is created, in the shape of an eight-pointed star. This path is then applied as a clip mask, and a
			radial gradient is painted over the bounding box of the star. The result is a star shape that is filled with a gradient.
		</p>
		
		<p>
			This sample can be improved by making the star a stencil (see <a href="Images_stencils.html">Images and stencils</a>), as in the
			following code:
		</p>
			
<div class="sampleCode">Rectangle bounds = new Rectangle(0,0,30,30);
Stencil starStencil = g.CreateStencil(bounds.Width, bounds.Height);

starStencil.Graphics.SetClip(star);

starStencil.Graphics.FillRectangle(
    new RadialGradientBrush(Rgb.White, Rgb.Yellow, bounds), bounds);

g.DrawStencil(starStencil, 100, 100);</div>			
	
		<h3>Example #2 - Decorated text</h3>
		
		<p>
			The code creates a clip mask in the shape of some text, and then plots yellow dots on a green
			background. Because of the clip mask, the dots and the background apply to just the area
			covered by the text. The result is spotted text. To emphasise the effect, the text is
			rendered in capitals and in a bold-face font.
		</p>
		
		<div class="sampleCode">Rectangle textBounds = new Rectangle(5, 10, 300, 70);

g.SetClip(
    "SPOTS", 
    new Font("Arial bold"), 50, textBounds.Left, textBounds.Top);

g.FillRectangle(Rgb.DarkGreenBrush, textBounds);

Rectangle spotBounds = new Rectangle(5, 10, 10, 10);
bool odd = true;
while(spotBounds.Top &lt; textBounds.Bottom)
{
    while(spotBounds.Left &lt; textBounds.Right)
    {
        g.FillEllipse(Rgb.BlueBrush, spotBounds);
        spotBounds.Move(20, 0);
    }

    spotBounds.Move(0, 10);
    spotBounds.Left = 5;
    if (odd) spotBounds.Move(10, 0);
    odd = !odd;
}</div>
			
		<img src="../images/Clipping_Special2.jpg" />
			
		<h3><strong>Navigation options:</strong></h3>
		<p><a href="Gradients.html">&lt; Gradients</a> | <a href="Colour_schemes.html">Colour schemes &gt;</a>
		
	</body>
	
</html>